home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / kcl / akcl / kcl.lha / doc / kclunix next >
Text File  |  1986-06-28  |  22KB  |  537 lines

  1.             Note on KCL/UNIX
  2.  
  3. This note is intended to be read by the users of KCL/UNIX, particularly
  4. of KCL/SUN and KCL/VAX.  It describes some problems of KCL/UNIX and how
  5. to avoid them by using the KCL/UNIX-specific features.
  6.  
  7.  
  8. * Core Dump
  9.  
  10. We can consider several situations in which KCL dumps core on UNIX.
  11.  
  12. 1. The KCL compiler, by default, produces efficient but very
  13. dangerous code.  The code seldom detects erroneous situations
  14. such as extracting the car of a fixnum, which, in bad cases,
  15. cause "Segmentation violation" or "Bus error" on UNIX.  To avoid this,
  16. you should tell the compiler to produce rather inefficient but safe
  17. code using the appropriate proclamation such as
  18.  
  19.     (proclaim '(optimize (safety 2))).
  20.  
  21. The safety level greater than or equal to 2 guarantees that the
  22. code detects every runtime error.
  23.  
  24. 2. KCL keeps several stacks.  Whenever an item is pushed on a
  25. stack, KCL checks whether the stack limit is violated or not,
  26. except for the value stack and the C stack.  The limit for the
  27. value stack is not checked if the code was compiled with the
  28. safety level 0; i.e., the limit is checked in the code compiled
  29. with the safety level greater than 0, and in the interpreted code.
  30.  
  31. 3. The limit for the C stack is not checked in the compiled code.
  32.  
  33. Note: KCL on BSD prepares the function SI:CATCH-BAD-SIGNALS which
  34. installs the signal catcher for bad signals of UNIX:
  35.  
  36.     SIGILL, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS.
  37.  
  38. If you want to catch these signals, call SI:CATCH-BAD-SIGNALS with
  39. no arguments.  When a signal is caught, KCL signals a Lisp error:
  40.  
  41.     Error: Signal 11 caught.
  42.  
  43. However, these signals mean that the internal memory of KCL may be
  44. broken.  You should check the signal and exit from KCL if necessary.
  45. When a signal is caught during garbage collection, KCL terminates
  46. immedately.
  47.  
  48. SI:UNCATCH-BAD-SIGNALS will undo the effect.
  49.  
  50.  
  51. * C Stack Limit
  52.  
  53. On BSD, you can specify the size of the C stack by the limit command
  54. of csh.  KCL sets the C stack limit slightly smaller than the actual
  55. stack size.  Therefore, for those applications that use much stack area,
  56. one can invoke KCL in the following way:
  57.  
  58.     % limit stacksize 1024        # 1024K bytes = 1M bytes
  59.     % kcl
  60.  
  61. Note: KCL will not extend the C stack size by itself.
  62.  
  63. Note: On SUN-3, the stack size is 512K bytes by default.
  64.  
  65. Note: When KCL detects the C stack overflow, it will signal a Lisp error
  66. except in the garbage collector.  When the C stack overflows during
  67. garbage collection, KCL terminates immediately.
  68.  
  69. Note: Big lists extending to the direction of car consume more stack
  70. area than those extending to cdr during garbage collection.
  71.  
  72.  
  73. * Process Size
  74.  
  75. Since KCL keeps a table which records the type of each page in the
  76. process space, the process size of KCL is limited to the size of
  77. the table.  Usually, the limit is set to 32M bytes on BSD, although it
  78. can be easily changed by re-installing KCL.
  79.  
  80. On BSD, the size of the KCL process is further limited by the resource
  81. limit set by the limit command of csh.  KCL does not change the limit by
  82. itself.
  83.  
  84. Note: Even if the resource limit is large, you cannot use that much
  85. because of the limitation of the swap space.  For example, on Sun-3,
  86. you can hardly allocate 10M bytes in the standard installation.
  87.  
  88. Note: The process size KCL understands is held in the variable
  89. SI:*LISP-MAXPAGES* in pages.
  90.  
  91.  
  92. * Explicit Expansion of Process Space
  93.  
  94. Usually, KCL expands its process space dynamically.  In order to
  95. allow the user to expand the process space of KCL immedately, the
  96. function ALLOCATE and ALLOCATE-CONTIGUOUS-PAGES take one optional
  97. argument.  When a non-NIL value is supplied for the optional argument,
  98. these functions acutally allocate the maximum number of pages for the
  99. specified implementation type or for the contiguous blocks.  Therefore,
  100. you can begin with 1M bytes for conses (500 pages = 1M bytes) as follows:
  101.  
  102.     % kcl
  103.     KCL (Kyoto Common Lisp) ...
  104.  
  105.     >(allocate 'cons 500 t)
  106.     t
  107.  
  108.     >
  109.  
  110. Note: This facility is not specific to KCL/UNIX.
  111.  
  112.  
  113. * Hole Size
  114.  
  115. The size of the hole between the heap and relocatable area (see Section
  116. 4.2 of the KCL Report) highly affects the performance of memory management.
  117. With the smaller size of hole, garbage collection occurs more frequently,
  118. but the total size of the (logical) memory used by KCL is kept smaller.
  119. We prepare the following functions so that the user can set up the
  120. "appropriate size" of his own.
  121.  
  122. (SI:GET-HOLE-SIZE) returns as an integer the hole size (in pages).
  123. Note that this is NOT the size of the current hole, but IS the size
  124. of the hole immediately after each garbage collection.
  125.  
  126. (SI:SET-HOLE-SIZE <fixnum>) sets the hole size.  <fixnum> is the
  127. new size of the hole (in pages).  <fixnum> must be a positive fixnum.
  128.  
  129. To see how frequently the garbage collection occurs, set the variable
  130. SI:*NOTIFY-GBC* to a non-NIL value.
  131.  
  132. Note: This feature is not specific to KCL/UNIX.
  133.  
  134.  
  135. * Notification of garbage collection
  136.  
  137. When the value of the system-internal variable SI:*NOTIFY-GBC* is
  138. non-NIL, the garbage collector will print
  139.  
  140.     GBC invoked
  141.  
  142. when it is invoked, and will print
  143.  
  144.     GBC finished
  145.  
  146. when it returns.
  147.  
  148. Note: The message is directly written on the standard output and is
  149. not written on a Lisp stream.  Therefore, when one DRIBBLEs the KCL
  150. session, the message from the garbage collector will not be written out
  151. on the specified file.
  152.  
  153.  
  154. * Big C Code
  155.  
  156. The C compiler sometimes complains that the code produced by KCL is too
  157. big and cannot compute jump addresses.  To avoid this, you should supply
  158. the assembler with the -J option as follows.
  159.  
  160. Compile the Lisp file by
  161.  
  162.     >(compile-file "foo.lsp" :c-file t :h-file t :data-file t
  163.                    :o-file nil)
  164.  
  165. and compile the C file with the -S option
  166.  
  167.     % cc -S foo.c
  168.  
  169. and then assemble it with the -J option.
  170.  
  171.     % as -J foo.s -o foo.o
  172.  
  173. Finally, concatenate the data file at the end.
  174.  
  175.     % cat foo.data >> foo.o
  176.  
  177.  
  178. * Faslink
  179.  
  180. The loader SI:FASLINK loads the object file while linking other object
  181. files and/or libraries.  It is used as follows:
  182.  
  183.     (si:faslink "foo.o" "bar.o boo.o -lpixrect")
  184.  
  185. "foo.o" should be an object file produced by compiling a Lisp source file.
  186. The Lisp file usually consists of DEFENTRY definitions that call
  187. functions in the object files and/or the libraries specified in the
  188. second argument.  The first argument should be a pathname, a string or a
  189. symbol, and the second argument should be a string that can be accpted by
  190. the UNIX linkage editor.  If there are more than one arguments, they
  191. should be separated by a space as above.
  192.  
  193. Note: The second argument is passed to "ld" as it is.
  194.  
  195. Note: SI:FASLINK is only defined in the BSD versions of KCL.
  196.  
  197. Example:
  198.  
  199. test.lsp:
  200.  
  201.     (defentry c-shift (int int) (int c_shift))
  202.     (defentry gamma (double) (double gamma))
  203.  
  204. shift.c:
  205.  
  206.     c_shift(x, y)
  207.     int x, y;
  208.     {
  209.         return(x << y);
  210.     }
  211.  
  212. Then,
  213.  
  214.     >(si:faslink "test" "shift.o -lm -lc")
  215.  
  216. will define C-SHIFT and GAMMA as intended.  Note that "test.lsp" should have
  217. been compiled.
  218.  
  219.  
  220. * Initial File
  221.  
  222. If there exists a file with the name "init.lsp" in the current directory,
  223. KCL loads the file before entering into the top-level loop.  The user
  224. of KCL is expected to make his/her own environment using this facility.
  225. It is similar to ".chsrc" for csh, ".profile" for sh, or ".newsrc" for
  226. readnews, although the name of the KCL initial file does not begin with ".".
  227.  
  228. For example, if you want to invoke your favorate editor from KCL, you can
  229. define the interface in "init.lsp".
  230.  
  231. Example of init.lsp:
  232.  
  233.     (setq si:*ignore-eof-on-terminal-io* t)
  234.     (setq si:*notify-gbc* t)
  235.     (si:catch-bad-signals)
  236.     (defun cd (file) (si:chdir file))
  237.     (defun exit (&optional (code 0)) (bye code))
  238.     (defvar *editor* (if (si:getenv "EDITOR") (si:getenv "EDITOR") "vi"))
  239.     (defun ed (&optional (file "gazonk"))
  240.       (system (format nil "~A ~A" *editor* (namestring file))))
  241.  
  242. Note: All the system-internal functions and variables that appear in the
  243. above example are explained in this note.
  244.  
  245.  
  246. * Ignoring EOF
  247.  
  248. The KCL top-level terminates when the standard input becomes end-of-file.
  249. If you do not like this feature, assign a non-NIL value to the system-internal
  250. variable SI:*IGNORE-EOF-ON-TERMINAL-IO*.  Then the stream *TERMINAL-IO* never
  251. becomes end-of-file.
  252.  
  253.  
  254. * Chdir
  255.  
  256. To change the current working directory of KCL, use the function
  257. SI:CHDIR.
  258.  
  259.     (SI:CHDIR "../foo")
  260.  
  261. will change the current directory to "../foo".
  262.  
  263.  
  264. * Environment
  265.  
  266. The environment of the KCL process is obtained by the function SI:GETENV.
  267. SI:GETENV is the Lisp equivalent to the C library "getenv".
  268. (SI:GETENV <string>) returns the value for the specified string in the
  269. environment, or NIL, if the string is not found.
  270.  
  271.  
  272. * Listen
  273.  
  274. LISTEN is implemented on BSD.  READ-CHAR-NO-HANG is also implemented,
  275. but it does not follow the Common Lisp Manual completely.
  276.  
  277.  
  278. * Summary of Useful System-interernal Functions and Variables
  279.  
  280. We extract useful system-internal functions and variables from the KCL
  281. Dictionary.  These include all the functions and variables explained so far.
  282.  
  283. ------------------------------------------------------------------------------
  284. si:address                                                          [Function]
  285.  
  286. Args: (object)
  287. KCL specific: Returns the address of the OBJECT as a fixnum.  The address of
  288. an object depends on the version of KCL.  E.g. (SI:ADDRESS NIL) returns
  289. 1879062044 on KCL/AOSVS dated March 14, 1986.
  290. ------------------------------------------------------------------------------
  291. si:argc                                                             [Function]
  292.  
  293. Args: ()
  294. KCL specific: Returns the number of arguments on the command line that invoked
  295. the KCL process.
  296. ------------------------------------------------------------------------------
  297. si:argv                                                             [Function]
  298.  
  299. Args: (fixnum)
  300. KCL specific: Returns the FIXNUM-th argument on the command line that invoked
  301. the KCL process.
  302. ------------------------------------------------------------------------------
  303. si:catch-bad-signals                                                [Function]
  304.  
  305. Args: ()
  306. KCL/BSD specific: Installs a signal catcher for bad signals:
  307.     SIGILL, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS.
  308. The signal catcher, upon catching the signal, signals an error (and enter
  309. the break-level).  Since the internal memory of KCL may be broken, the user
  310. should check the signal and exit from KCL if necessary.  When the signal
  311. is caught during garbage collection, KCL terminates immediately.
  312. ------------------------------------------------------------------------------
  313. si:chdir                                                            [Function]
  314.  
  315. Args: (pathname)
  316. KCL/UNIX specific: Changes the current working directory to the specified
  317. pathname.
  318. ------------------------------------------------------------------------------
  319. si:compiled-function-name                                           [Function]
  320.  
  321. Args: (compiled-function-object)
  322. KCL specific: Returns the name of the COMPILED-FUNCTION-OBJECT.
  323. ------------------------------------------------------------------------------
  324. si:copy-stream                                                      [Function]
  325.  
  326. Args: (in-stream out-stream)
  327. KCL specific: Copies IN-STREAM to OUT-STREAM until the end-of-file on IN-
  328. STREAM.
  329. ------------------------------------------------------------------------------
  330.  
  331. ------------------------------------------------------------------------------
  332. si:*default-time-zone*                                              [Variable]
  333.  
  334. KCL specific: Holds the default time zone.  The initial value of SI:*DEFAULT-
  335. TIME-ZONE* is -9 (the time zone of Japan).
  336. ------------------------------------------------------------------------------
  337. si:displaced-array-p                                                [Function]
  338.  
  339. Args (array)
  340. KCL specific: Returns T if the ARRAY is a displaced array; NIL otherwise.
  341. ------------------------------------------------------------------------------
  342. si:error-set                                                        [Function]
  343.  
  344. Args: (form)
  345. KCL specific: Evaluates the FORM in the null environment.  If the evaluation
  346. of the FORM has successfully completed, SI:ERROR-SET returns NIL as the first
  347. value and the result of the evaluation as the rest of the values.  If, in the
  348. course of the evaluation, a non-local jump from the FORM is atempted,
  349. SI:ERROR-SET traps the jump and returns the corresponding jump tag as its
  350. value.
  351. ------------------------------------------------------------------------------
  352. si:faslink                                                          [Function]
  353.  
  354. Args: (file string)
  355. KCL/BSD specific: Loads the FASL file FILE while linking the object files and
  356. libraries specified by STRING.  For example,
  357.     (faslink "foo.o" "bar.o boo.o -lpixrect")
  358. loads foo.o while linking two object files (bar.o and boo.o) and the library
  359. pixrect.  Usually, foo.o consists of the C language interface for the
  360. functions defined in the object files or the libraries.
  361. ------------------------------------------------------------------------------
  362. si:fixnump                                                          [Function]
  363.  
  364. Args: (object)
  365. KCL specific: Returns T if the OBJECT is a fixnum; NIL otherwise.
  366. ------------------------------------------------------------------------------
  367. si:get-string-input-stream-index                                    [Function]
  368.  
  369. Args: (string-input-stream)
  370. KCL specific: Returns the current index of the STRING-INPUT-STREAM.
  371. ------------------------------------------------------------------------------
  372. si:getenv                                                           [Function]
  373.  
  374. Args: (string)
  375. KCL/UNIX specific: Returns the environment with the name STRING as a string;
  376. if the environment specified by STRING is not found, returns NIL.
  377. ------------------------------------------------------------------------------
  378. si:get-hole-size                                                    [Function]
  379.  
  380. Args: ()
  381. KCL specific: Returns as a fixnum the size of the memory hole (in pages).
  382. ------------------------------------------------------------------------------
  383.  
  384. ------------------------------------------------------------------------------
  385. si:*ignore-eof-on-terminal-io*                                      [Variable]
  386.  
  387. KCL specific: If the value of SI:*IGNORE-EOF-ON-TERMINAL-IO* is non-NIL, KCL
  388. ignores the eof-character (usually ^D) on the terminal and the terminal never
  389. becomes end-of-file.  The default value of SI:*IGNORE-EOF-ON-TERMINAL-IO* is
  390. NIL.
  391. ------------------------------------------------------------------------------
  392. si:*indent-formatted-output*                                        [Variable]
  393.  
  394. KCL specific: The FORMAT directive ~% indents the next line if the value of
  395. this variable is non-NIL.  If NIL, ~% simply does Newline.
  396. ------------------------------------------------------------------------------
  397. si:init-system                                                      [Function]
  398.  
  399. Args: ()
  400. KCL specific: Initializes the library and the compiler of KCL.  Since they
  401. have already been initialized in the standard image of KCL, calling SI:INIT-
  402. SYSTEM will cause an error.
  403. ------------------------------------------------------------------------------
  404. si:*interrupt-enable*                                               [Variable]
  405.  
  406. KCL specific: If the value of SI:*INTERRUPT-ENABLE* is non-NIL, KCL signals
  407. an error on the terminal interrupt (this is the default case).  If it is NIL,
  408. KCL ignores the interrupt and assigns T to SI:*INTERRUPT-ENABLE*.
  409. ------------------------------------------------------------------------------
  410. si:*lisp-maxpages*                                                  [Variable]
  411.  
  412. KCL specific: Holds the maximum number of pages (1 page = 2048 bytes) for the
  413. KCL process.  The result of changing the value of SI:*LISP-MAXPAGES* is
  414. unpredictable.
  415. ------------------------------------------------------------------------------
  416. si:*make-constant                                                   [Function]
  417.  
  418. Args: (symbol value)
  419. KCL specific: Makes the SYMBOL a constant with the specified VALUE.
  420. ------------------------------------------------------------------------------
  421. si:*make-special                                                    [Function]
  422.  
  423. Args (symbol)
  424. KCL specific: Makes the SYMBOL globally special.
  425. ------------------------------------------------------------------------------
  426.  
  427. ------------------------------------------------------------------------------
  428. si:make-string-output-stream-from-string                            [Function]
  429.  
  430. Args (string)
  431. KCL specific: Creates a string-output-stream corresponding to the STRING and
  432. returns it.  The STRING should have a fill-pointer.
  433. ------------------------------------------------------------------------------
  434. si:nani                                                             [Function]
  435.  
  436. Args: (fixnum)
  437. KCL specific: Returns the object in the address FIXNUM.  This function is
  438. the inverse of SI:ADDRESS.  Although SI:ADDRESS is a harmless operation,
  439. SI:NANI is quite dangerous and should be used with care.
  440. ------------------------------------------------------------------------------
  441. si:*notify-gbc*                                                     [Variable]
  442.  
  443. KCL specific: If the value of this variable is non-NIL, then the garbage
  444. collector notifies that it begins to run whenever it is invoked.  Otherwise,
  445. garbage collection begins silently.
  446. ------------------------------------------------------------------------------
  447. si:output-stream-string                                             [Function]
  448.  
  449. Args: (string-output-stream)
  450. KCL specific: Returns the string corresponding to the STRING-OUTPUT-STREAM.
  451. ------------------------------------------------------------------------------
  452. si:reset-gbc-count                                                  [Function]
  453.  
  454. Args: ()
  455. KCL specific: Resets the counter of the garbage collector that records how
  456. many times the garbage collector has been called for each implementation
  457. type.
  458. ------------------------------------------------------------------------------
  459. si:reset-stack-limits                                               [Function]
  460.  
  461. Args: ()
  462. KCL specific: Resets the stack limits to the normal state.  When a stack has
  463. overflowed, KCL extends the limit for the stack in order to execute the error
  464. handler.  After processing the error, KCL resets the stack limit by calling
  465. SI:RESET-STACK-LIMITS.
  466. ------------------------------------------------------------------------------
  467. si:save-system                                                      [Function]
  468.  
  469. Args: (pathname)
  470. KCL specific: Saves the current KCL core imange into a program file specified
  471. by PATHNAME.  This function differs from SAVE in that the contiguous and
  472. relocatable areas are made permanent in the saved image.  Usually the
  473. standard image of KCL interpreter/compiler is saved by SI:SAVE-SYSTEM.
  474. ------------------------------------------------------------------------------
  475. si:set-hole-size                                                    [Function]
  476.  
  477. Args: (fixnum)
  478. KCL specific: Sets the size of the memory hole (in pages).
  479. ------------------------------------------------------------------------------
  480. si:specialp                                                         [Function]
  481.  
  482. Args: (symbol)
  483. KCL specific: Returns T if the SYMBOL is a globally special variable; NIL
  484. otherwise.
  485. ------------------------------------------------------------------------------
  486.  
  487. ------------------------------------------------------------------------------
  488. si:string-concatenate                                               [Function]
  489.  
  490. Args: (&rest strings)
  491. KCL specific: Returns the result of concatenating the given STRINGS.
  492. ------------------------------------------------------------------------------
  493. si:string-to-object                                                 [Function]
  494.  
  495. Args: (string)
  496. KCL specific: (SI:STRING-TO-OBJECT STRING) is equivalent to
  497. (READ-FROM-STRING STRING), but much faster.
  498. ------------------------------------------------------------------------------
  499. si:structurep                                                       [Function]
  500.  
  501. Args: (object)
  502. KCL specific: Returns T if the OBJECT is a structure; NIL otherwise.
  503. ------------------------------------------------------------------------------
  504. si:*system-directory*                                               [Variable]
  505.  
  506. KCL specific: Holds the name of the system directory of KCL.
  507. ------------------------------------------------------------------------------
  508. si:top-level                                                        [Function]
  509.  
  510. Args: ()
  511. KCL specific: Starts the standard top-level listner of KCL.  When the KCL
  512. process is invoked, it calls SI:TOP-LEVEL by (FUNCALL 'SI:TOP-LEVEL).
  513.      To change the top-level of KCL, redefine SI:TOP-LEVEL and save the core
  514. imange in a file.  When the saved imange is invoked, it will start the
  515. redefined top-level.
  516. ------------------------------------------------------------------------------
  517. si:universal-error-handler                                          [Function]
  518.  
  519. Args: (error-name correctable function-name
  520.        continue-format-string error-format-string
  521.        &rest args)
  522. KCL specific: Starts the error handler of KCL.  When an error is detected,
  523. KCL calls SI:UNIVERSAL-ERROR-HANDLER with the specified arguments.
  524. ERROR-NAME is the name of the error.  CORRECTABLE is T for a correctable
  525. error and NIL for a fatal error.  FUNCTION-NAME is the name of the function
  526. that caused the error.  CONTINUE-FORMAT-STRING and ERROR-FORMAT-STRING are
  527. the format strings of the error message.  ARGS are the arguments to the
  528. format strings.
  529.      To change the error handler of KCL, redefine SI:UNIVERSAL-ERROR-
  530. HANDLER.
  531. ------------------------------------------------------------------------------
  532. si:uncatch-bad-signals                                              [Function]
  533.  
  534. Args: ()
  535. KCL/BSD specific: Undoes the effect of SI:CATCH-BAD-SIGNALS.
  536. ------------------------------------------------------------------------------
  537.